<!DOCTYPE html>
<title>Getting started - nearley.js - JS Parsing Toolkit</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="nearley.js is a simple, fast, and powerful parser toolkit for JavaScript." />
<style>
body {
    font-family: BlinkMacSystemFont, -apple-system, Helvetica Neue, Open Sans, Ubuntu, Arial, Helvetica, sans-serif;
    font-weight: 300;
    font-size: 15pt;
    margin: 0px;
    padding: 0px;
}

#main a {
    color: #55a;
}
#main a:visited {
    color: #55a;
}
#main a:hover {
    color: #259;
}

h1 {
    font-size: 1.2em;
    font-weight: normal;
    letter-spacing: 0.2em;
    text-align: center;
    margin:  0em;
    padding: 1em;
}

h1 a {
    color: #559;
    text-decoration: none;
}

h1 a:hover {
    color: orange;
    cursor: pointer;
}

#version {
    background: orange;
    border-radius: 50%;
    font-weight: bold;
    color: white;
    width: 3em;
    height: 3em;
    display: inline-block;
    text-align: center;
    line-height: 3em;
    letter-spacing: 0em;
}

h2 {
    font-size: 1.5em;
    margin-top: 2em;
}
h3 {
    margin-top: 3em;
}
h4 {
    margin-top: 3em;
}

.center {
    padding-left: 2em;
    padding-right: 2em;
    margin-left: auto;
    margin-right: auto;
}
#main {
    max-width: 35em;
}

#main p, ul, ol {
    line-height: 1.5em;
    margin-bottom: 1em;
}

#main li {
    margin-top: 1em;
    margin-bottom: 1em;
}

#main ul li {
    list-style: none;
    min-width: 10em;
}
#main ul li:before {
    display: inline-block;
    content: "\2014";
    margin-left: -1.5em;
    width: 1.5em;
    position: absolute;
}

#main textarea {
    width: 100%;
    height: 20em;
    resize: none;
    margin-top: 5px;
    margin-bottom: 5px;

    font-family: menlo, monaco, monospace;
    font-size: 10pt;
    padding: 5px;

    border: none;
    border-left: solid 1px #aaa;
}
#main textarea:focus {
    outline: none;
}

#main img {
    display: block;
    margin-left: auto;
    margin-right: auto;
    max-width: 100%;
}
img + .caption {
    text-align: center;
    font-size: 0.7em;
    color: #aaa;
}

#footer {
    margin-top: 10em;
    color: #aaa;
    font-size: 0.7em;
    padding: 5em;
}

code {
    margin-left: 0.2em;
    margin-right: 0.2em;
    padding: 0.2em;
    border-radius: 0.2em;
    background-color: #eee;
}

pre code {
    border-radius: 0.5em;
    padding: 0.5em;
    display: block;
    overflow: auto;
}


ol {
    counter-reset: tutorial-counter;
    position: relative;
}

ol li {
    list-style: none;
}

ol li:before {
    content: counter(tutorial-counter);
    counter-increment: tutorial-counter;

    font-weight: bold;
    border-radius: 50%;
    background-color: #559;
    width: 2em;
    height: 2em;
    display: inline-block;
    text-align: center;
    line-height: 2em;
    color: white;

    margin-left: -2em;

    position: absolute;
    left: 1em;
}

input[type="text"] {
    border: none;
    font-family: monospace;
    font-size: 1em;
    color: #559;
}

input[type="text"]:focus {
    outline: none;
}


nav {
    border-bottom: 2px solid #559;
    background: #fafafa;
}
nav ul {
    padding: 0;
    margin: 0;
}
nav ul a {
    text-decoration: none;
    color: #334;
    display: block;
    overflow: hidden;
    text-overflow: ellipsis;
    padding: 0.25em 0.5em; */
}
.page {
    display: block;
}

.page-title-active,
.page-heading-active a {
    color: #66f;
}

.page-heading {
    display: block;
    padding-left: 1.5em;
}


@media screen and (min-width: 36rem) {
    nav {
        position: fixed;
        width: 16rem;
        left: 0;
        top: 0;
        bottom: 0;
        white-space: nowrap;
        overflow-y: auto;
        font-size: 1rem;
        border-bottom: none;
        border-right: 2px solid #559;
    }
    body.docs-page {
        margin-left: 16rem;
    }
}

/* highlight.js */

.hljs{display:block;overflow-x:auto;padding:0.5em;background:#F0F0F0}.hljs,.hljs-subst{color:#444}.hljs-comment{color:#888888}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-selector-pseudo{color:#BC6060}.hljs-literal{color:#78A960}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta-string{color:#4d99bf}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}


</style>

<body class="docs-page">

<a href="https://github.com/kach/nearley" class="github-corner"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
<nav id="nav">
    <h1><a href="/">nearley<span style="color: #559;">.js</span><span id="version">2.20.1</span></a></h1>
    <ul>
        <li class="page"><a href="/docs/index">Home</a>
        <li class="page">
            <a href="#" class="page-title-active">Getting started</a>
            <ul>
                <li class="page-heading"><a href="#installation">Installation</a>
                <li class="page-heading"><a href="#nearley-in-3-steps">nearley in 3 steps</a>
                <li class="page-heading"><a href="#whats-next">What’s next?</a>
                <li class="page-heading"><a href="#further-reading">Further reading</a>
            </ul>
        </li>
        <li class="page"><a href="/docs/grammar">Writing a parser</a>
        <li class="page"><a href="/docs/parser">Using a parser</a>
        <li class="page"><a href="/docs/tokenizers">Tokenizers</a>
        <li class="page"><a href="/docs/tooling">Tooling</a>
        <li class="page"><a href="/docs/how-to-grammar-good">How to grammar good</a>
        <li class="page"><a href="/docs/using-in-frontend">Compiling in browsers</a>
        <li class="page"><a href="/docs/glossary">Glossary</a>
    </ul>
</nav>

<div id="main" class="center">

<h2>Getting started</h2>
<p>nearley consists of two components: a <em>compiler</em> and a <em>parser</em>.</p>
<p>The nearley <em>compiler</em> converts grammar definitions from a simple
<a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a>-based syntax to a small
JS module. You can then use that module to construct a nearley <em>parser</em>, which
parses input strings.</p>
<h3 id="installation">Installation</h3>
<p>Both components are published as a single
<a href="https://docs.npmjs.com/getting-started/what-is-npm">NPM</a> package compatible
with <a href="https://nodejs.org/en/">Node.js</a> and most browsers.</p>
<p>To use the nearley <em>parser</em>, you need to install nearley <strong>locally</strong>.</p>
<pre><code class="language-bash">$ npm install --save nearley</code></pre>
<p>To use the nearley <em>compiler</em>, you need to <em>additionally</em> install nearley
<strong>globally</strong>.</p>
<pre><code class="language-bash">$ npm install -g nearley</code></pre>
<p>This actually adds several new commands to your <code>$PATH</code>:</p>
<ul>
<li><code>nearleyc</code> compiles grammar files to JavaScript.</li>
<li><code>nearley-test</code> lets you quickly test a grammar against some input and see the
results. It also lets you explore the internal state of nearley’s Earley
table, in case you find that interesting.</li>
<li><code>nearley-unparse</code> inverts a parser into a generator, allowing you to create
random strings that match your grammar.</li>
<li><code>nearley-railroad</code> generates pretty railroad diagrams from your parser. This
is mainly helpful for creating documentation, as (for example) on json.org.</li>
</ul>
<p>These are documented on the <a href="tooling">tooling page</a>.</p>
<blockquote>
<p>Note: If you’re not ready to install nearley yet, you can follow along in
your browser using the <a href="https://omrelli.ug/nearley-playground/">nearley
playground</a>, an online interface for
exploring nearley grammars interactively.</p>
</blockquote>
<h3 id="nearley-in-3-steps">nearley in 3 steps</h3>
<p>nearley was written with users in mind: getting started with nearley is as
simple as:</p>
<p><strong>Step 1: Describe your grammar</strong> using the <a href="grammar">nearley syntax</a>. In
a file called <code>grammar.ne</code>, write:</p>
<pre><code class="language-ne">main -&gt; (statement &quot;\n&quot;):+
statement -&gt; &quot;foo&quot; | &quot;bar&quot;</code></pre>
<p><strong>Step 2: Compile</strong> the grammar to a JavaScript module. On the command line,
run:</p>
<pre><code class="language-bash">$ nearleyc grammar.ne -o grammar.js</code></pre>
<p><strong>Step 3: Parse</strong> some data! In a new JavaScript file, instantiate a <a href="parser">Parser
object</a> and feed it a string:</p>
<pre><code class="language-js">const nearley = require(&quot;nearley&quot;);
const grammar = require(&quot;./grammar.js&quot;);

// Create a Parser object from our grammar.
const parser = new nearley.Parser(nearley.Grammar.fromCompiled(grammar));

// Parse something!
parser.feed(&quot;foo\n&quot;);

// parser.results is an array of possible parsings.
console.log(JSON.stringify(parser.results)); // [[[[[&quot;foo&quot;],&quot;\n&quot;]]]]</code></pre>
<h3 id="whats-next">What’s next?</h3>
<p>Now that you have nearley installed, you can <a href="grammar">learn how to write a
grammar</a>!</p>
<h3 id="further-reading">Further reading</h3>
<ul>
<li>Take a look at a <a href="https://medium.com/@gajus/parsing-absolutely-anything-in-javascript-using-earley-algorithm-886edcc31e5e">nearley
tutorial</a>
written by @gajus, or a <a href="http://humans-who-read-grammars.blogspot.com/2018/04/having-fun-with-phrase-structure.html">blog post about using nearley-unparse to generate
murder mystery
plots</a>.</li>
<li>Read my <a href="http://hardmath123.github.io/earley.html">blog post</a> to learn more
about the algorithm.</li>
<li>Read about <a href="http://savage.net.au/Marpa.html">Marpa</a> to learn more than you
ever thought you wanted to know about parsing.</li>
</ul>


    <div id="footer"><p>nearley is MIT-licensed. It's maintained by <a
    href="http://hardmath123.github.io">Hardmath123</a> (<a
    href="http://github.com/Hardmath123">Github</a>). You're welcome to
    leave questions, comments, advice, or ideas as Github issues. And
    feel free to fork nearley with your own experiments!<br/>
    
    <a href="https://js.org" target="_blank" title="JS.ORG | JavaScript Community">
    <img src="https://logo.js.org/dark_horz.png" width="102" alt="JS.ORG Logo"/></a>
</div>

<script id="highlight-js" async src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
<script>
document.querySelector('#highlight-js').addEventListener('load', function() {
    [].slice.apply(document.querySelectorAll('pre code')).forEach(function(b) {
        hljs.highlightBlock(b)
    })
})
</script>


<script>
window.addEventListener('scroll', onScroll)
window.addEventListener('resize', onScroll)

var timeout
function onScroll(e) {
    if (timeout) clearTimeout(timeout)
    timeout = setTimeout(scrollEnd, 50)
}

function scrollEnd() {
  var headings = document.querySelectorAll('h3')
  var offset = 60
  for (var i=headings.length; i--; ) {
    var h3 = headings[i]
    if (h3.offsetTop < window.scrollY + offset) {
      var cur = document.querySelector('.page-heading-active')
      if (cur) cur.className = 'page-heading'
      document.querySelector('a[href="#' + h3.id + '"]').parentNode.className = 'page-heading page-heading-active'
      return
    }
  }
}
</script>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-46120535-5', 'auto');
ga('send', 'pageview');
</script>

